用户登录接口

一、应用场景

用户登录是指物联云平台C端用户的登录认证服务。包含物联云平台密码登录、手机验证码登录、第三方平台用户登录、二维码授权登录。企业可根据实际场景选择登录方式，并完成与物联云平台的对接。以实现不同场景下提供给用户平台登录服务。

  • 用户通过输入邮箱/手机号、密码的方式进行登录。

  • 用户通过手机号和手机接收到的验证码进行登录。

  • 用户通过第三方平台身份进行登录。

  • 用户在应用终端（室内机）通过二维码授权进行完成登录。

二、功能说明

企业可通过实际场景选择提供给用户的登录方式。根据选用的登录方式进行对接。

物联云平台密码登录：支持通过物联云平台中已创建用户的邮箱/手机号和密码进行登录，邮箱和手机号二选一，优先使用手机号。
手机验证码登录：支持通过物联云平台中已创建用户的手机号和手机验证码进行登录，用户获取验证码次数超过限额后，需要同时输入图片验证码进行登录。
第三方平台用户登录：非主流第三方平台可查看第三方用户说明进行开发对应接口，并将接口地址配置在物联云平台【应用中心->集成->免登录验证】中。完成与物联云平台的联调后，用户可通过第三方平台身份进行登录。
二维码授权登录：应用终端（室内机）可获取二维码信息，用户扫描终端上的二维码进行登录。

三、前提条件

1.通过物联云平台登录，需要完成用户信息的创建。
2.通过第三方平台登录，需要完成与物联云平台的对接。

四、关键流程

4.1 用户调用凭证管理

流程说明：

  • 首先，C端APP用户登录到物联网中台，获取到物联网中台的调用凭证以及刷新凭证。
  • 其次，C端APP用户使用物联网中台刷新凭证发起 通过刷新凭证换取调用凭证 请求。
  • 再次，物联网中台接收到 通过刷新凭证换取调用凭证 请求，进行换取物联网中台新调用凭证业务逻辑操作，返回新的物联网中台调用凭证以及刷新凭证。
  • 接着，C端APP用户使用物联网中台调用凭证发起 失效用户调用凭证 请求。
  • 最后，物联网中台接收到 失效用户调用凭证 请求，进行失效物联网中台调用凭证以及刷新凭证业务逻辑。

用户调用凭证管理

4.2 用户短信登录

流程说明：

  • 首先，C端APP用户 获取手机短信验证码，分两种情况：
    • 手机号获取短信验证码次数未超过企业设置的阈值，则正常获取到手机短信验证码。
    • 手机号获取短信验证码次数超过企业设置的阈值，则需要发起 **C端APP用户获取手机图片验证码 **请求，得到手机图片验证码后再次发起 C端APP用户获取手机短信验证码 请求。
  • 其次，C端APP用户根据上一步操作接收到的手机短信验证码发起 短信登录 请求。
  • 再次，物联网中台接收到 短信登录 请求，校验手机验证码的有效性以及手机号的合法性等业务逻辑操作。
  • 最后，物联网中台返回物联网中台调用凭证和刷新凭证。

用户短信登录

4.3 二维码授权登录

流程说明：

  • 首先，应用终端根据配置的应用标识和应用秘钥进行 应用网关登录，得到物联网中台应用级调用凭证。
  • 其次，应用终端根据应用级调用凭证进行 应用终端申请授权二维码，得到二维码信息以及二维码有效期。
  • 再次，应用终端根据二维码信息渲染二维码到应用终端的屏幕上，进而定时循环请求 应用终端查询授权二维码 得到二维码是否被授权。
  • 接着，C端APP用户登录到物联网中台得到用户级调用凭证后，扫描应用终端的二维码得到二维码信息向物联网中台发起 用户端校验授权二维码 ，从而得到应用终端期望被授权的权限以及信息，用户决定是否进行授权。
  • 最后，C端APP用户决定授权给应用终端，应用终端通过定时循环请求 应用终端查询授权二维码 得到应用物联网中台用户级调用凭证，使用该凭证查询应用终端访问物联网中台基础信息进行终端渲染。

二维码授权登录

4.4 用户OAuth2登录

流程说明：

  • 首先，第三方应用（如天猫精灵）请求物联网中台用户信息会被重定向到物联网中台OAuth2特定页面，要求物联网中台C端用户输入账号密码进行登录得到用户级调用凭证后，向物联网中台发起 申请临时授权码 请求，得到临时授权码返回给第三方应用。
  • 其次，第三方应用（如天猫精灵）根据上一步得到的临时授权码向物联网中台发起 临时授权码登录 请求 从而得到物联网中台用户级调用凭证，该凭证与正常用户登录得到的调用凭证有权限上的区别。
  • 最后，第三方应用（如天猫精灵）根据物联网中台用户级临时调用凭证访问物联网中台进行基础信息获取。

用户OAuth2登录

4.5 第三方用户登录

流程说明：

  • 首先，C端APP用户首先登录到第三方平台，获取到第三方平台的调用凭证以及第三方平台标识。

  • 其次，C端APP用户根据第三方平台的调用凭证和第三方平台标识发起 第三方用户登录 请求。

  • 再次，物联网中台接收到登录请求，根据第三方平台的调用凭证以及第三方平台标识向第三方平台发起校验，分两种情况：

    • 第三方平台为主流第三方平台时，物联网中台直接向第三方平台发起校验获取用户信息。
    • 第三方平台为物联云平台标准第三方平台时，物联网中台查询到第三方平台的服务地址发起校验获取用户信息。

  • 接着，物联网中台根据第三方标识查询第三方平台用户是否已在物联网中台内，如不在则创建一个新的C端APP用户记录进行持久化。

  • 最后，物联网中台为第三方平台标识对应的C端APP用户输出物联网中台调用凭证和刷新凭证。

  • 物联云平台第三方标准平台定义

    第三方用户登录

4.6 绑定手机第三方用户登录

流程说明：

  • 首先，C端APP用户首先登录到第三方平台，获取到第三方平台的调用凭证以及第三方平台标识。
  • 其次，C端APP用户在APP上输入要绑定的手机号，同时向物联网中台发起请求手机验证码，将收到的手机验证码填入APP进行登录；由于企业设置了一个手机号码一天内获取验证码的阈值之后，需要通过图片验证码才能获取手机验证码，因此如果被限流之后APP需要向物联网中台获取图片验证码。
  • 再次，C端APP用户根据第三方平台的调用凭证和第三方平台标识发起 绑定手机第三方用户登录 请求。
  • 接着，物联网中台接收到登录请求校验手机验证码的有效性，根据第三方平台的调用凭证以及第三方平台标识向第三方平台发起校验，分两种情况：
    • 第三方平台为主流第三方平台时，物联网中台直接向第三方平台发起校验获取用户信息。
    • 第三方平台为物联云平台标准第三方平台时，物联网中台查询到第三方平台的服务地址发起校验获取用户信息。
  • 接着，物联网中台根据第三方标识查询第三方平台用户是否已在物联网中台内，如不在则创建一个新的C端APP用户记录进行持久化，同时绑定手机号。
  • 最后，物联网中台为第三方平台标识对应的C端APP用户输出物联网中台调用凭证和刷新凭证。
  • 物联云平台第三方标准平台定义

绑定手机第三方用户登录

4.7 国外第三方用户登录

流程说明：

  • 首先，C端APP用户首先登录到Facebook/Twitter第三方平台，获取到Facebook/Twitter第三方平台的调用凭证以及第三方平台标识；需要注意 目前主要适用于facebook和twitter两种第三方登录；其中facebook使用oauth2.0验证；twitter使用oauth1.0验证。
  • 其次，C端APP用户根据Facebook/Twitter第三方平台的调用凭证和第三方平台标识发起 国外第三方用户登录 请求。
  • 再次，物联网中台接收到登录请求，根据Facebook/Twitter第三方平台调用凭证以及第三方平台标识向Facebook/Twitter第三方平台发起校验且获取用户信息。
  • 接着，物联网中台根据第三方标识查询第三方平台用户是否已在物联网中台内，如不在则创建一个新的C端APP用户记录进行持久化。
  • 最后，物联网中台为第三方平台标识对应的C端APP用户输出物联网中台调用凭证和刷新凭证。

国外第三方用户登录

4.8 用户临时密码登录

流程说明：

  • 首先，C端APP用户在忘记密码的情况下向物联网中台发起 **通过邮件申请临时密码 ** 请求。
  • 其次，C端APP用户 查看邮箱邮件得到临时密码。
  • 再次，C端APP用户 在App中填入临时密码向物联网中台发起 使用临时密码登录 请求得到用户级调用凭证。
  • 最后，C端APP用户 使用用户级调用凭证向物联网中台查询用户相关信息渲染App。

用户临时密码登录

五、API列表

5.1 用户账号登录

5.1.1 手机邮箱账号登录

接口描述

C端用户通过手机号码或者邮箱进行登录，登录成功后获取到平台的调用凭证以及刷新凭证用于调用其他相关接口；参数邮箱手机二选一，手机号优先

请求方式

POST

请求地址

/v2/user_auth

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
corp_id body true String 企业标识
phone body false String 用户手机号
phone_zone body false String 用户手机号区号
email body false String 用户邮箱
password body true String 用户密码
resource body false String 用户登录源

请求示例：

{
	"corp_id": "452565dfd2e4fsdf2",
	"phone": "13838383388",
	"phone_zone": "+86",
	"email": "liqinghua@xlink.cn",
	"password": "Test@#$%^",
	"resource": "TEST"
}

返回参数说明

名称 必填 类型 备注
user_id true Int 用户标识
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证有效期，单位秒
authorize true String 用户认证码

返回示例：

{
    "user_id": 4512326,
    "access_token": "1254sfs456edfd546e54",
    "refresh_token": "1254sfs456edfd546e54",
    "expire_in": 7200,
    "authorize": "123ed54ffffer"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041010 企业不存在
4041011 用户不存在
4001124 账号未初始化密码
4001061 账号已被锁定, 多次输入错误密码导致
4001083 企业处于迁移状态
4001007 账号密码错误
4001008 帐号不合法

5.1.2 通过刷新凭证换取调用凭证

接口描述

C端用户通过刷新凭证换取调用凭证

请求方式

POST

请求地址

/v2/user/token/refresh

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
refresh_token body true String 平台刷新凭证

请求示例：

{
    "refresh_token": "edf656fd2f564sdf89"
}

返回参数说明

名称 必填 类型 备注
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证有效期，单位秒

返回示例：

{
    "access_token": "edf656fd2edsfsdffds45efd156445",
    "refresh_token": "edf656fd2f564sdf89efd156445",
    "expire_in": 7200
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4001010 刷新凭证非法
4041011 用户不存在
4001083 企业处于迁移状态
4001008 帐号不合法

5.1.3 失效用户调用凭证

接口描述

在第三方系统修改了用户的密码以及授权关系之后，发起清除用户的调用凭证，主要用于第三方用户登录体系的场景，调用方一般为SaaS系统而非管理台或者C端用户

请求方式

POST

请求地址

/v2/users/token/clear

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
平台权限
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
resource body false String 用户登录源
user_id body true Int 用户标识

请求示例：

{
    "resource": "TEST",
    "user_id": 856412366
}

返回参数说明

名称 必填 类型 备注
无 无 无 无

返回示例：

{
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041011 用户不存在
4041114 调用凭证不存在

5.2 用户短信登录

5.2.1 短信登录–获取手机短信验证码

接口描述

C端用户通过手机号码+认证码进行登录之前，需要使用手机号码获取到一个有效的登录验证码，用于调用后续的登录接口；当用户手机获取验证码次数超过了企业设置的限额后，需要提供图片验证码参数

请求方式

POST

请求地址

/v2/user_auth_sms/verifycode

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业成员
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
corp_id body true String 企业标识
phone body true String 用户手机号码
phone_zone body true String 用户手机区号
captcha body false String 图片验证码
plugin_id body false String 用户所在的应用标识

请求示例：

{
    "corp_id": "456ed1f2d5f4fffdfd",
    "phone": "13838383388",
    "phone_zone": "+86",
    "captcha": "563146",
    "plugin_id": "54646sdfafdfdf564"
}

返回参数说明

名称 必填 类型 备注
无 无 无 无

返回示例：

{
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4001052 手机今日发送短信的次数已达上限
4001456 一小时内发送短信太频繁
4001498 一分钟内发送短信太频繁
4041020 应用不存在

5.2.2 短信登录–获取手机图片验证码

接口描述

C端用户通过手机号码获取验证码时，由于获取次数超过企业设置因此需要获取图片验证码用于防止机器刷接口

请求方式

POST

请求地址

/v2/user_auth_sms/captcha

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
corp_id body true String 企业标识
phone body true String 用户手机号码
phone_zone body true String 用户手机区号

请求示例：

{
    "corp_id": "45618974dsedccdscg66",
    "phone": "13838383388",
    "phone_zone": "+86"
}

返回参数说明

名称 必填 类型 备注
url true String 图片验证码地址

返回示例：

{
    "url": "http://www.baidu.com"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041020 应用不存在

5.2.3 短信登录

接口描述

C端用户通过手机号码+认证码进行登录，手机号账号不存在时用户将自动创建

请求方式

POST

请求地址

/v2/user_auth_sms

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
corp_id body true String 企业标识
phone body true String 用户手机号码
phone_zone body true String 用户手机区号
verifycode body true String 手机验证码
resource body true String 用户登录源

请求示例：

{
    "corp_id": "561346dfs456efd13f",
    "phone": "13838383388",
    "verifycode": "856325",
    "resource": "TEST",
    "phone_zone": "+86"
}

返回参数说明

名称 必填 类型 备注
user_id true String 用户标识
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证的有效期
authorize true String 用户认证码
is_register true Boolean 是否是新注册的用户

返回示例：

{
    "user_id": 79456542,
    "access_token": "sdfsd54e65d1f25456fsedddf",
    "refresh_token": "sdfsd54srfdftr344536fsef",
    "expire_in": 7200,
    "authorize": "23er43efdsff23",
    "is_register": true
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041010 企业不存在
4041011 用户不存在
4001124 账号未初始化密码
4001061 账号已被锁定, 多次输入错误密码导致
4001083 企业处于迁移状态
4001007 账号密码错误
4001008 帐号不合法

5.3 二维码授权登录

5.3.1 应用网关应用登录

接口描述

设备终端根据配置的应用标识和应用秘钥进行登录，获得应用级别调用凭证；其中应用标识和应用秘钥在企业管理的应用中心处获取

请求方式

POST

请求地址

/v2/plugin/app_auth

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业用户
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
app_id body true String 应用标识
app_secret body true String 应用秘钥

请求示例：

{
    "app_id": "54654123dsfewfdf213",
    "app_secret": "5465sfawedsfewfdf213"
}

返回参数说明

名称 必填 类型 备注
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证有效期，单位秒

返回示例：

{
    "access_token": "156465sfsdfwef123sdfsdf",
    "refresh_token": "1651sdafwefd123fd5sg4f65g4",
    "expire_in": 7200
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041020 应用不存在
4001137 应用未启用
4031011 应用秘钥不正确

5.3.2 应用终端申请授权二维码

接口描述

应用终端(室内机)通过应用级别调用凭证申请二维码信息，其中应用必须为网关类型应用

请求方式

POST

请求地址

/v2/qrcode/user-auth

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
应用权限
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
app_id body true String 应用标识
secret body true String 二维码私钥
expire body false Int 二维码有效分钟数, 默认5分钟, 最大不能超过45分钟
client_id body false String 客户端标识，长度为1~16
主要用于标识同一个客户端生成二维码时会覆盖掉相同client_id的上一个二维码
非必填, 需要兼容之前App未传该字段的线上应用
extend_data body false Object 二维码拓展信息

请求示例：

{
    "app_id": "156e1d3fdf56456fdf",
    "secret": "161sf2wefd2ddf",
    "expire": 5,
    "client_id": "sfsdwdfdsfdsfsdfa",
    "extend_data": {
        "name": "室内机"
    }
}

返回参数说明

名称 必填 类型 备注
id true String 二维码标识
content true String 二维码内容, 目前和二维码标识一样
utc_server_time true String UTC系统时间
expire true String 二维码过期时间, 单位分钟

返回示例：

{
    "id": "1456111dsf1afe5fgd",
    "content": "1456111dsf1afe5fgd",
    "utc_server_time": "2019-12-16T16:00:00.000Z",
    "expire": 1
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041020 应用不存在
4001330 APP应用不属于网关应用

5.3.3 应用终端查询授权二维码

接口描述

应用终端(室内机)定时轮循通过二维码秘钥和二维码标识查询二维码的信息，从而确认二维码是否被用户授权确认；如果二维码已经被授权确认则会发回相对应的C端用户凭证

请求方式

GET

请求地址

/v2/qrcode/user-auth/{qr_id}?secret=xxxx

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
应用权限
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
qr_id path true String 二维码标识
secret query true String 二维码秘钥

请求示例：

{
}

返回参数说明

名称 必填 类型 备注
status true Int 二维码状态
0:待授权
1:拒绝
2:同意
3:扫描未确认
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire true Int 调用凭证有效期，单位秒
user_id true Int 用户标识
resources true Object 用户授权给应用端的资源, 由各款App自定义

返回示例：

{
    "status": 2,
    "access_token": "156465sfsdfwef123sdfsdf",
    "refresh_token": "1651sdafwefd123fd5sg4f65g4",
    "expire": 7200,
    "user_id": 216549874515,
    "resources": {
        "name":"室内机"
    }
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041020 应用不存在
4001330 APP应用不属于网关应用

5.3.4 用户端校验授权二维码

接口描述

应用终端在申请到二维码信息之后，生成二维码展示出来，C端用户扫描二维码从而得到二维码的内容，从而对授权二维码进行校验，调用接口后会由待授权状态变为扫描未确认状态

请求方式

POST

请求地址

/v2/qrcode/user-valid

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业用户
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
content body true String 二维码内容

请求示例：

{
    "content": "sd11we23fewf123dsfe5f1dfd"
}

返回参数说明

名称 必填 类型 备注
qrcode_id true String 二维码标识
app_infos true String 应用信息
app_infos.name true String 应用名称
extend_data true Object 二维码拓展信息
interfaces true Object 供选择的二维码授权接口信息
interfaces.categorys.code true String 授权类别编号
interfaces.categorys.name true String 授权类别名称

返回示例：

{
    "qrcode_id": "123s54fef1d2f3e5f4d2f5dfd5",
    "app_infos": {
        "name": "网关应用"
    },
    "extend_data": {
        "name": "室内机"
    },
    "interfaces": {
        "categorys": [{
            "code": "10001",
            "name": "产品列表"
        }]
    }
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041020 应用不存在
4001330 APP应用不属于网关应用
4001392 用户授权登录二维码内容非法
4041104 用户授权登录二维码不存在

5.3.5 用户端对二维码授权登录

接口描述

用户端通过二维码进行登录授权，只有状态为待授权或者扫描未确认时才可以授权

请求方式

POST

请求地址

/v2/qrcode/user-auth/{qr_id}/grant

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业用户
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
qr_id path true String 二维码标识
status body true Int 授权二维码状态
1:拒绝
2:同意
expire body true Int 授权有效时间，单位秒
resources body false Object 授权额外资源，由各款APP自定义
interfaces body false Object 授权接口列表
interfaces.categorys body false Array 授权接口类别编码

请求示例：

{
    "status": 2,
    "expire": 7200,
    "interfaces": {
        "categorys": ["10001"]
    },
    "resources": {
        "name":"室内机"
    }
}

返回参数说明

名称 必填 类型 备注
无 无 无 无

返回示例：

{
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041020 应用不存在
4001330 APP应用不属于网关应用
4001395 用户授权登录二维码已授权
4041104 用户授权登录二维码不存在
4001393 用户授权状态无法识别
4001394 用户授权接口类别非法

5.4 用户OAuth2登录

5.4.1 申请临时授权码

接口描述

C端用户在已登录的情况下获取临时授权码；授权码有效期为3分钟；同一个登录源resource同一时间只能有一个授权码，重复提交会进行覆盖；登录源resource不能与当前AccessToken的登录源相同

请求方式

POST

请求地址

/v2/user/oauth2/apply-authcode

请求头

名称 必填 类型 备注
Access-Token true String 调用凭证
企业用户
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
resource body true String 用户登录源

请求示例：

{
    "resource":"TEST"
}

返回参数说明

名称 必填 类型 备注
auth_code true String 临时授权码

返回示例：

{
    "auth_code":"dsf156123e12fds15fdsf6f6d5"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足

5.4.2 临时授权码登录

接口描述

第三方系统根据5.2.1获取到的临时授权码之后，根据临时授权码换取C端用户的调用凭证

请求方式

POST

请求地址

/v2/user/oauth2/exchange-access-token

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
auth_code body true String 临时授权码

请求示例：

{
     "auth_code":"dsf156123e12fds15fdsf6f6d5"
}

返回参数说明

名称 必填 类型 备注
user_id true Int 用户标识
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证有效期，单位秒
authorize true String 用户认证码

返回示例：

{
    "user_id": 785613232,
    "access_token": "dfaef123156f46dsfed54ff",
    "refresh_token": "ef1df156e4w65fd1f1d2f1d2",
    "expire_in": 7200,
    "authorize": "dsfefd123sf156"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足

5.5 第三方用户登录

5.5.1 第三方用户登录

接口描述

用户在通过了第三方平台登录成功后，通过第三方openId、accessToken在物联云平台请求登录，如果第三方用户不在物联云平台则直接创建一个用户，如果已在物联云平台则更新相关信息．

请求方式

POST

请求地址

/v2/user_auth_third

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
source body true Int 用户第三方源
4: 微信
5: QQ
6: 微博
7: FaceBook
8: 推特
10: 其他
12: Apple
13: google
plugin_id body false String 应用标识
当source为Apple时，该项必传，需要根据此项去查找对应的苹果client_id和client_secret
当source为Google时，该项必传，需要根据此项去查找对应的谷歌的client_id
open_id body true String 第三方用户标识
当source为Google时，可不传或随意传不以传参为准，会从google的authCode中解析得到, google开发者中心不建议直接传user_id
corp_id body true String 企业标识
access_token body true String 第三方调用凭证
当source为Apple时，accessToken为苹果auth2认证中的authorization code
当source为Google时，accessToken不是真实的Google AccessToken，而是Google临时授权码authCode
name body false String 用户名称
resource body false String 用户登录源

请求示例：

{
    "source": 4,
    "corp_id": "1235aed1f1df222",
    "open_id":"156s1fe6d123fef15d1d2",
    "access_token":"1112sdfwefdsfafd212",
    "name":"李清华",
    "resource":"TEST",
    "plugin_id":"131566efdfaew23"
}

返回参数说明

名称 必填 类型 备注
user_id true String 用户标识
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证的有效期
authorize true String 用户认证码

返回示例：

{
    "user_id":112356456,
    "access_token":"dsfs16we1d1fd23afew5fdf",
    "refresh_token":"1561ewfd1s2fwe5fffdfdsfsdf",
    "expire_in":7200,
    "authorize":"dsfe1561d56fds1fe"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4001482 第三方源未知
4041020 应用不存在
4041023 未设置第三方登录地址
4001059 第三方验证失败
4041010 企业不存在
4001477 IOS没有配置Apple登录
4001478 调用Apple超时
4001479 调用Apple失败
4001480 Apple Jwt过期
4001481 Apple授权码非法
4001483 APP未启用Apple登录
4001137 APP未启用

5.5.2 绑定手机第三方用户登录

接口描述

用户在通过了第三方平台登录成功后，通过openId、accessToken在物联云平台请求登录，如果第三方用户不在物联云平台则直接创建一个用户，如果已在物联云平台则更新相关信息，与此同时绑定该用户的手机号码．如果通过5.9.4检测出已经绑定了手机号码，则可以直接使用5.9.5接口进行登录

请求方式

POST

请求地址

/v2/user/third/auth-bind-phone

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
source body true Int 用户第三方源
4: 微信
5: QQ
6: 微博
7: FaceBook
8: 推特
10: 其他
12: Apple
13: google
plugin_id body false String 应用标识
当source为Apple时，该项必传，需要根据此项去查找对应的苹果client_id和client_secret
当source为Google时，该项必传，需要根据此项去查找对应的谷歌的client_id
open_id body true String 第三方用户标识
当source为Google时，可不传或随意传不以传参为准，会从google的authCode中解析得到, google开发者中心不建议直接传user_id
corp_id body true String 企业标识
access_token body true String 第三方调用凭证
当source为Apple时，accessToken为苹果auth2认证中的authorization code
当source为Google时，accessToken不是真实的Google AccessToken，而是Google临时授权码authCode
name body false String 用户名称
resource body false String 用户登录源
phone body true String 绑定的手机号码
verifycode body true String 绑定的手机号码的验证码
phone_zone body false String 绑定的手机区号，默认为+86

请求示例：

{
    "source": 4,
    "corp_id": "1515wddad2332f",
    "open_id":"111116554afdaed23ee",
    "access_token":"14564f56fsdf32fsdfsdaf",
    "name":"李清华",
    "resource":"TEST",
    "plugin_id":"51356efdf12df",
    "phone":"13838383388",
    "phone_zone":"+86",
    "verifycode":"123563"
}

返回参数说明

名称 必填 类型 备注
user_id true String 用户标识
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证的有效期
authorize true String 用户认证码

返回示例：

{
    "user_id":12356465,
    "access_token":"562233sdffdsf1s3f2sdfg234r",
    "refresh_token":"sfffff23345563rfa234436346",
    "expire_in":7200,
    "authorize":"dsf564sfgg"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4001482 第三方源未知
4041020 应用不存在
4041023 未设置第三方登录地址
4001059 第三方验证失败
4041010 企业不存在
4001477 IOS没有配置Apple登录
4001478 调用Apple超时
4001479 调用Apple失败
4001480 Apple Jwt过期
4001481 Apple授权码非法
4001483 APP未启用Apple登录
4001137 APP未启用
4001003 手机验证码不存在
4001004 手机验证码错误

5.5.3 国外的第三方用户登录

接口描述

由于国外网络访问限制原因导致该接口的存在，目前主要适用于facebook和twitter两种第三方登录；其中facebook使用oauth2.0验证；twitter使用oauth1.0验证，验证用户的接口是https://api.twitter.com/1.1/users/show.json?user_id={twitter_user_id}(客户端构造oauth_signature时需要用到)

请求方式

POST

请求地址

/v2/user_auth_third_foreign

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
source body true Int 用户第三方源
7: FaceBook
8: 推特
12: Apple
13: google
plugin_id body false String 应用标识
当source为Apple时，该项必传，需要根据此项去查找对应的苹果client_id和client_secret
当source为Google时，该项必传，需要根据此项去查找对应的谷歌的client_id
open_id body true String 第三方用户标识
当source为Google时，可不传或随意传不以传参为准，会从google的authCode中解析得到, google开发者中心不建议直接传user_id
corp_id body true String 企业标识
access_token body true String 第三方调用凭证
当source为Apple时，accessToken为苹果auth2认证中的authorization code
当source为Google时，accessToken不是真实的Google AccessToken，而是Google临时授权码authCode
name body false String 用户名称
resource body false String 用户登录源
oauth_version body true String oauth版本.值为1.0或者2.0
oauth_consumer_key body false String 注册应用后由应用服务商提供（如果oauth_version为1.0，必须提供）
oauth_nonce body false String 随机字符串，须保证每次都不同（如果oauth_version为1.0，必须提供）
oauth_timestamp body false String 时间戳（如果oauth_version为1.0，必须提供）
oauth_signature_method body false String 签名base string 的方法，目前支持 HMAC-SHA1（如果oauth_version为1.0，必须提供）
oauth_signature body false String 签名值（如果oauth_version为1.0，必须提供）

请求示例：

{
    "source": 7,
    "corp_id": "12564dsf56efsdf",
    "open_id":"651fs1f25frdfsd",
    "access_token":"1fsd545rf56f15a1d",
    "name":"李清华",
    "resource":"TEST",
    "plugin_id":"12365a6efcdf23r43115",
    "oauth_version":"1.0",
    "oauth_consumer_key":"DC0sePOBbQ8bYdC8r4Smg",
    "oauth_signature_method":"HMAC-SHA1",
    "oauth_timestamp":"1477446586",
    "oauth_nonce":"1130669700",
    "oauth_signature":"PAWOXPqbWK13rL%2F5QrWfKcLRfKs%3D"
}

返回参数说明

名称 必填 类型 备注
user_id true String 用户标识
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证的有效期
authorize true String 用户认证码

返回示例：

{
    "user_id":56562231,
    "access_token":"dsf156sa1f65r532r561f561fsdf",
    "refresh_token":"165sd15f11eaw5d32rfdsfdsd",
    "expire_in":7200,
    "authorize":"111sd23f3rfdf1sd32f"
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4001482 第三方源未知
4041020 应用不存在
4041023 未设置第三方登录地址
4001059 第三方验证失败
4041010 企业不存在
4001477 IOS没有配置Apple登录
4001478 调用Apple超时
4001479 调用Apple失败
4001480 Apple Jwt过期
4001481 Apple授权码非法
4001483 APP未启用Apple登录
4001137 APP未启用
4001003 手机验证码不存在
4001004 手机验证码错误

5.6 用户临时密码登录

5.6.1 通过邮件申请临时密码

接口描述

用户在忘记密码的情况下，可以通过邮件申请临时密码并且使用临时密码进行登录；该临时密码有效期为一个小时, 并且一个邮箱一个小时内只能申请两次临时密码；目前只有RB客户在使用

请求方式

POST

请求地址

/v2/user/temp_password/send/email

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
corp_id body true String 企业标识
email body true String 邮箱地址
language body true String 指定邮件的语言,预留字段,目前只支持英文en-us

请求示例：

{
    "corp_id":"51231654fdsffwefdf",
    "email":"liqinghua@xlink.cn",
    "language":"en-us"
}

返回参数说明

名称 必填 类型 备注
无 无 无 无

返回示例：

{
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041010 企业不存在
4041011 用户不存在
4001032 用户邮箱未认证
4001432 用户申请临时密码超过限制

5.6.2 使用临时密码登录

接口描述

用户在通过邮箱申请得到临时密码之后，使用临时密码进行登录；与此同时，该接口兼容了原始密码登录功能, 也就是说使用原始密码和临时密码均可以使用该接口进行登录；目前只有RB客户在使用

请求方式

POST

请求地址

/v2/user_auth/temp_password

请求头

名称 必填 类型 备注
Content-Type true String application/json

请求参数

名称 位置 必填 类型 备注
corp_id body true String 企业标识
phone body false String 手机号码
phone_zone body false String 手机区号，使用手机号码登录时可选。
email body false String 邮箱地址
password body true String 登录原始密码或者临时密码
resource body true String 用户登录源

请求示例：

{
    "corp_id": "1234565e4f5dff",
    "phone": "13838383388",
    "phone_zone": "+86",
    "email": "liqinghua@xlink.cn",
    "password": "Test@#$%^&",
    "resource": "TEST"
}

返回参数说明

名称 必填 类型 备注
user_id true Int 用户标识
access_token true String 调用凭证
refresh_token true String 刷新凭证
expire_in true Int 调用凭证有效期，单位秒
authorize true String 用户认证码
is_temp_password true Boolean 是否使用临时密码登录

返回示例：

{
    "user_id": 123535554,
    "access_token": "123565sdfsfsf4dsfsd45gggg",
    "refresh_token": "123565sdfsfsf4dsfefdfwef",
    "expire_in": 7200,
    "authorize": "4562112sdfsdfsd",
    "is_temp_password": true,
}

错误码：

错误码 描述
4001001 请求数据字段验证不通过
4001002 请求数据必须字段不可为空
4031001 调用凭证权限被禁止访问
4031003 无效的调用凭证
4031002 需要调用凭证
4041001 接口不存在
5031001 系统错误
4031024 权限不足
4041010 企业不存在
4041011 用户不存在
4001124 账号未初始化密码
4001061 账号已被锁定, 多次输入错误密码导致
4001083 企业处于迁移状态
4001007 账号密码错误
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题